home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 52 / Amiga Format AFCD52 (Issue 136, May 2000).iso / -serious- / programming / c / icu-1.3.1 / icu-bin / include / simpletz.h < prev    next >
C/C++ Source or Header  |  2000-02-23  |  23KB  |  472 lines
  1. /*
  2. ********************************************************************************
  3. *                                                                              *
  4. * COPYRIGHT:                                                                   *
  5. *   (C) Copyright Taligent, Inc.,  1997                                        *
  6. *   (C) Copyright International Business Machines Corporation,  1997-1999           *
  7. *   Licensed Material - Program-Property of IBM - All Rights Reserved.         *
  8. *   US Government Users Restricted Rights - Use, duplication, or disclosure    *
  9. *   restricted by GSA ADP Schedule Contract with IBM Corp.                     *
  10. *                                                                              *
  11. ********************************************************************************
  12. *
  13. * File SIMPLETZ.H
  14. *
  15. * Modification History:
  16. *
  17. *   Date        Name        Description
  18. *   04/21/97    aliu        Overhauled header.
  19. *    08/10/98    stephen        JDK 1.2 sync
  20. *                            Added setStartRule() / setEndRule() overloads
  21. *                            Added hasSameRules()
  22. *    09/02/98    stephen        Added getOffset(monthLen)
  23. *                            Changed getOffset() to take UErrorCode
  24. *    07/09/99    stephen     Removed millisPerHour (unused, for HP compiler)
  25. ********************************************************************************
  26. */
  27.  
  28. #ifndef SIMPLETZ_H
  29. #define SIMPLETZ_H
  30.  
  31. #include "timezone.h"
  32.  
  33. /**
  34.  * <code>SimpleTimeZone</code> is a concrete subclass of <code>TimeZone</code>
  35.  * that represents a time zone for use with a Gregorian calendar. This
  36.  * class does not handle historical changes.
  37.  * <P>
  38.  * When specifying daylight-savings-time begin and end dates, use a negative value for
  39.  * <code>dayOfWeekInMonth</code> to indicate that <code>SimpleTimeZone</code> should
  40.  * count from the end of the month backwards. For example, in the U.S., Daylight Savings
  41.  * Time ends at the last (dayOfWeekInMonth = -1) Sunday in October, at 2 AM in standard
  42.  * time.
  43.  *
  44.  * @see      Calendar
  45.  * @see      GregorianCalendar
  46.  * @see      TimeZone
  47.  * @version  1.24 10/30/97
  48.  * @author   David Goldsmith, Mark Davis, Chen-Lieh Huang, Alan Liu
  49.  */
  50. class U_I18N_API SimpleTimeZone: public TimeZone {
  51. public:
  52.  
  53.     /**
  54.      * Copy constructor
  55.      */
  56.     SimpleTimeZone(const SimpleTimeZone& source);
  57.  
  58.     /**
  59.      * Default assignment operator
  60.      */
  61.     SimpleTimeZone& operator=(const SimpleTimeZone& right);
  62.  
  63.     /**
  64.      * Destructor
  65.      */
  66.     virtual ~SimpleTimeZone();
  67.  
  68.     /**
  69.      * Returns true if the two TimeZone objects are equal; that is, they have
  70.      * the same ID, raw GMT offset, and DST rules.
  71.      *
  72.      * @param that  The SimpleTimeZone object to be compared with.
  73.      * @return      True if the given time zone is equal to this time zone; false
  74.      *              otherwise.
  75.      */
  76.     virtual bool_t operator==(const TimeZone& that) const;
  77.  
  78.     /**
  79.      * Constructs a SimpleTimeZone with the given raw GMT offset and time zone ID,
  80.      * and which doesn't observe daylight savings time.  Normally you should use
  81.      * TimeZone::createInstance() to create a TimeZone instead of creating a
  82.      * SimpleTimeZone directly with this constructor.
  83.      *
  84.      * @param rawOffset  The given base time zone offset to GMT.
  85.      * @param ID         The timezone ID which is obtained from
  86.      *                   TimeZone.getAvailableIDs.
  87.      */
  88.     SimpleTimeZone(int32_t rawOffset, const UnicodeString& ID);
  89.  
  90.     /**
  91.      * Construct a SimpleTimeZone with the given raw GMT offset, time zone ID,
  92.      * and times to start and end daylight savings time. To create a TimeZone that
  93.      * doesn't observe daylight savings time, don't use this constructor; use 
  94.      * SimpleTimeZone(rawOffset, ID) instead. Normally, you should use
  95.      * TimeZone.createInstance() to create a TimeZone instead of creating a
  96.      * SimpleTimeZone directly with this constructor.
  97.      * <P>
  98.      * Various types of daylight-savings time rules can be specfied by using different
  99.      * values for startDay and startDayOfWeek and endDay and endDayOfWeek.  For a
  100.      * complete explanation of how these parameters work, see the documentation for
  101.      * setStartRule().
  102.      *
  103.      * @param rawOffset       The new SimpleTimeZone's raw GMT offset
  104.      * @param ID              The new SimpleTimeZone's time zone ID.
  105.      * @param startMonth      The daylight savings starting month. Month is
  106.      *                        0-based. eg, 0 for January.
  107.      * @param startDay        The daylight savings starting
  108.      *                        day-of-week-in-month. See setStartRule() for a
  109.      *                        complete explanation.
  110.      * @param startDayOfWeek  The daylight savings starting day-of-week. See setStartRule()
  111.      *                        for a complete explanation.
  112.      * @param startTime       The daylight savings starting time, expressed as the
  113.      *                        number of milliseconds after midnight.
  114.      * @param endMonth        The daylight savings ending month. Month is
  115.      *                        0-based. eg, 0 for January.
  116.      * @param endDay          The daylight savings ending day-of-week-in-month.
  117.      *                        See setStartRule() for a complete explanation.
  118.      * @param endDayOfWeek    The daylight savings ending day-of-week. See setStartRule()
  119.      *                        for a complete explanation.
  120.      * @param endTime         The daylight savings ending time, expressed as the
  121.      *                        number of milliseconds after midnight.
  122.      * @param status          An UErrorCode to receive the status.
  123.      */
  124.     SimpleTimeZone(int32_t rawOffset, const UnicodeString& ID,
  125.         int8_t startMonth, int8_t startDayOfWeekInMonth,
  126.         int8_t startDayOfWeek, int32_t startTime,
  127.         int8_t endMonth, int8_t endDayOfWeekInMonth,
  128.         int8_t endDayOfWeek, int32_t endTime,
  129.         UErrorCode& status);
  130.  
  131.     SimpleTimeZone(int32_t rawOffset, const UnicodeString& ID,
  132.         int8_t startMonth, int8_t startDayOfWeekInMonth,
  133.         int8_t startDayOfWeek, int32_t startTime,
  134.         int8_t endMonth, int8_t endDayOfWeekInMonth,
  135.         int8_t endDayOfWeek, int32_t endTime,
  136.         int32_t dstSavings, UErrorCode& status);
  137.  
  138.     /**
  139.      * Sets the daylight savings starting year, that is, the year this time zone began
  140.      * observing its specified daylight savings time rules.  The time zone is considered
  141.      * not to observe daylight savings time prior to that year; SimpleTimeZone doesn't
  142.      * support historical daylight-savings-time rules.
  143.      * @param year the daylight savings starting year.
  144.      */
  145.     void setStartYear(int32_t year);
  146.  
  147.     /**
  148.      * Sets the daylight savings starting rule. For example, in the U.S., Daylight Savings
  149.      * Time starts at the first Sunday in April, at 2 AM in standard time.
  150.      * Therefore, you can set the start rule by calling:
  151.      * setStartRule(TimeFields.APRIL, 1, TimeFields.SUNDAY, 2*60*60*1000);
  152.      * The dayOfWeekInMonth and dayOfWeek parameters together specify how to calculate
  153.      * the exact starting date.  Their exact meaning depend on their respective signs,
  154.      * allowing various types of rules to be constructed, as follows:<ul>
  155.      *   <li>If both dayOfWeekInMonth and dayOfWeek are positive, they specify the
  156.      *       day of week in the month (e.g., (2, WEDNESDAY) is the second Wednesday
  157.      *       of the month).
  158.      *   <li>If dayOfWeek is positive and dayOfWeekInMonth is negative, they specify
  159.      *       the day of week in the month counting backward from the end of the month.
  160.      *       (e.g., (-1, MONDAY) is the last Monday in the month)
  161.      *   <li>If dayOfWeek is zero and dayOfWeekInMonth is positive, dayOfWeekInMonth
  162.      *       specifies the day of the month, regardless of what day of the week it is.
  163.      *       (e.g., (10, 0) is the tenth day of the month)
  164.      *   <li>If dayOfWeek is zero and dayOfWeekInMonth is negative, dayOfWeekInMonth
  165.      *       specifies the day of the month counting backward from the end of the
  166.      *       month, regardless of what day of the week it is (e.g., (-2, 0) is the
  167.      *       next-to-last day of the month).
  168.      *   <li>If dayOfWeek is negative and dayOfWeekInMonth is positive, they specify the
  169.      *       first specified day of the week on or after the specfied day of the month.
  170.      *       (e.g., (15, -SUNDAY) is the first Sunday after the 15th of the month
  171.      *       [or the 15th itself if the 15th is a Sunday].)
  172.      *   <li>If dayOfWeek and DayOfWeekInMonth are both negative, they specify the
  173.      *       last specified day of the week on or before the specified day of the month.
  174.      *       (e.g., (-20, -TUESDAY) is the last Tuesday before the 20th of the month
  175.      *       [or the 20th itself if the 20th is a Tuesday].)</ul>
  176.      * @param month the daylight savings starting month. Month is 0-based.
  177.      * eg, 0 for January.
  178.      * @param dayOfWeekInMonth the daylight savings starting
  179.      * day-of-week-in-month. Please see the member description for an example.
  180.      * @param dayOfWeek the daylight savings starting day-of-week. Please see
  181.      * the member description for an example.
  182.      * @param time the daylight savings starting time. Please see the member
  183.      * description for an example.
  184.      * @param status An UErrorCode
  185.      */
  186.     void setStartRule(int32_t month, int32_t dayOfWeekInMonth, int32_t dayOfWeek,
  187.                              int32_t time, UErrorCode& status);
  188.  
  189.     /**
  190.      * Sets the DST start rule to a fixed date within a month.
  191.      *
  192.      * @param month         The month in which this rule occurs (0-based).
  193.      * @param dayOfMonth    The date in that month (1-based).
  194.      * @param time          The time of that day (number of millis after midnight)
  195.      *                      when DST takes effect in local wall time, which is
  196.      *                      standard time in this case.
  197.      * @param status An UErrorCode
  198.      */
  199.     void setStartRule(int32_t month, int32_t dayOfMonth, int32_t time, 
  200.                         UErrorCode& status);
  201.  
  202.     /**
  203.      * Sets the DST start rule to a weekday before or after a give date within
  204.      * a month, e.g., the first Monday on or after the 8th.
  205.      *
  206.      * @param month         The month in which this rule occurs (0-based).
  207.      * @param dayOfMonth    A date within that month (1-based).
  208.      * @param dayOfWeek     The day of the week on which this rule occurs.
  209.      * @param time          The time of that day (number of millis after midnight)
  210.      *                      when DST takes effect in local wall time, which is
  211.      *                      standard time in this case.
  212.      * @param after         If true, this rule selects the first dayOfWeek on
  213.      *                      or after dayOfMonth.  If false, this rule selects
  214.      *                      the last dayOfWeek on or before dayOfMonth.
  215.      * @param status An UErrorCode
  216.      */
  217.     void setStartRule(int32_t month, int32_t dayOfMonth, int32_t dayOfWeek, 
  218.                         int32_t time, bool_t after, UErrorCode& status);
  219.  
  220.     /**
  221.      * Sets the daylight savings ending rule. For example, in the U.S., Daylight
  222.      * Savings Time ends at the last (-1) Sunday in October, at 2 AM in standard time.
  223.      * Therefore, you can set the end rule by calling:
  224.      * <pre>
  225.      * .   setEndRule(TimeFields.OCTOBER, -1, TimeFields.SUNDAY, 2*60*60*1000);
  226.      * </pre>
  227.      * Various other types of rules can be specified by manipulating the dayOfWeek
  228.      * and dayOfWeekInMonth parameters.  For complete details, see the documentation
  229.      * for setStartRule().
  230.      *
  231.      * @param month the daylight savings ending month. Month is 0-based.
  232.      * eg, 0 for January.
  233.      * @param dayOfWeekInMonth the daylight savings ending
  234.      * day-of-week-in-month. See setStartRule() for a complete explanation.
  235.      * @param dayOfWeek the daylight savings ending day-of-week. See setStartRule()
  236.      * for a complete explanation.
  237.      * @param time the daylight savings ending time. Please see the member
  238.      * description for an example.
  239.      * @param status An UErrorCode
  240.      */
  241.     void setEndRule(int32_t month, int32_t dayOfWeekInMonth, int32_t dayOfWeek,
  242.                            int32_t time, UErrorCode& status);
  243.  
  244.     /**
  245.      * Sets the DST end rule to a fixed date within a month.
  246.      *
  247.      * @param month         The month in which this rule occurs (0-based).
  248.      * @param dayOfMonth    The date in that month (1-based).
  249.      * @param time          The time of that day (number of millis after midnight)
  250.      *                      when DST ends in local wall time, which is daylight
  251.      *                      time in this case.
  252.      * @param status An UErrorCode
  253.      */
  254.     void setEndRule(int32_t month, int32_t dayOfMonth, int32_t time, UErrorCode& status);
  255.  
  256.     /**
  257.      * Sets the DST end rule to a weekday before or after a give date within
  258.      * a month, e.g., the first Monday on or after the 8th.
  259.      *
  260.      * @param month         The month in which this rule occurs (0-based).
  261.      * @param dayOfMonth    A date within that month (1-based).
  262.      * @param dayOfWeek     The day of the week on which this rule occurs.
  263.      * @param time          The time of that day (number of millis after midnight)
  264.      *                      when DST ends in local wall time, which is daylight
  265.      *                      time in this case.
  266.      * @param after         If true, this rule selects the first dayOfWeek on
  267.      *                      or after dayOfMonth.  If false, this rule selects
  268.      *                      the last dayOfWeek on or before dayOfMonth.
  269.      * @param status An UErrorCode
  270.      */
  271.     void setEndRule(int32_t month, int32_t dayOfMonth, int32_t dayOfWeek, 
  272.                         int32_t time, bool_t after, UErrorCode& status);
  273.  
  274.     /**
  275.      * Returns the TimeZone's adjusted GMT offset (i.e., the number of milliseconds to add
  276.      * to GMT to get local time in this time zone, taking daylight savings time into
  277.      * account) as of a particular reference date.  The reference date is used to determine
  278.      * whether daylight savings time is in effect and needs to be figured into the offset
  279.      * that is returned (in other words, what is the adjusted GMT offset in this time zone
  280.      * at this particular date and time?).  For the time zones produced by createTimeZone(),
  281.      * the reference data is specified according to the Gregorian calendar, and the date
  282.      * and time fields are in GMT, NOT local time.
  283.      *
  284.      * @param era        The reference date's era
  285.      * @param year       The reference date's year
  286.      * @param month      The reference date's month (0-based; 0 is January)
  287.      * @param day        The reference date's day-in-month (1-based)
  288.      * @param dayOfWeek  The reference date's day-of-week (1-based; 1 is Sunday)
  289.      * @param millis     The reference date's milliseconds in day, UTT (NOT local time).
  290.      * @return           The offset in milliseconds to add to GMT to get local time.
  291.      */
  292.     virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day,
  293.                               uint8_t dayOfWeek, int32_t millis, UErrorCode& status) const;
  294.  
  295.     virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day,
  296.                               uint8_t dayOfWeek, int32_t millis) const;
  297.  
  298.     /**
  299.      * Gets the time zone offset, for current date, modified in case of
  300.      * daylight savings. This is the offset to add *to* UTC to get local time.
  301.      * @param era the era of the given date.
  302.      * @param year the year in the given date.
  303.      * @param month the month in the given date.
  304.      * Month is 0-based. e.g., 0 for January.
  305.      * @param day the day-in-month of the given date.
  306.      * @param dayOfWeek the day-of-week of the given date.
  307.      * @param milliseconds the millis in day in <em>standard</em> local time.
  308.      * @param monthLength the length of the given month in days.
  309.      * @return the offset to add *to* GMT to get local time.
  310.      */
  311.     virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day,
  312.                            uint8_t dayOfWeek, int32_t milliseconds, 
  313.                            int32_t monthLength, UErrorCode& status) const;
  314.  
  315.     /**
  316.      * Returns the TimeZone's raw GMT offset (i.e., the number of milliseconds to add
  317.      * to GMT to get local time, before taking daylight savings time into account).
  318.      *
  319.      * @return   The TimeZone's raw GMT offset.
  320.      */
  321.     virtual int32_t getRawOffset(void) const;
  322.  
  323.     /**
  324.      * Sets the TimeZone's raw GMT offset (i.e., the number of milliseconds to add
  325.      * to GMT to get local time, before taking daylight savings time into account).
  326.      *
  327.      * @param offsetMillis  The new raw GMT offset for this time zone.
  328.      */
  329.     virtual void setRawOffset(int32_t offsetMillis);
  330.  
  331.     /**
  332.      * Sets the amount of time in ms that the clock is advanced during DST.
  333.      * @param millisSavedDuringDST the number of milliseconds the time is
  334.      * advanced with respect to standard time when the daylight savings rules
  335.      * are in effect. A positive number, typically one hour (3600000).
  336.      */
  337.     void setDSTSavings(int32_t millisSavedDuringDST, UErrorCode& status);
  338.  
  339.     // deprecated
  340.     void setDSTSavings(int32_t millisSavedDuringDST);
  341.  
  342.     /**
  343.      * Returns the amount of time in ms that the clock is advanced during DST.
  344.      * @return the number of milliseconds the time is
  345.      * advanced with respect to standard time when the daylight savings rules
  346.      * are in effect. A positive number, typically one hour (3600000).
  347.      */
  348.     int32_t getDSTSavings(void) const;
  349.  
  350.     /**
  351.      * Queries if this TimeZone uses Daylight Savings Time.
  352.      *
  353.      * @return   True if this TimeZone uses Daylight Savings Time; false otherwise.
  354.      */
  355.     virtual bool_t useDaylightTime(void) const;
  356.  
  357.     /**
  358.      * Returns true if the given date is within the period when daylight savings time
  359.      * is in effect; false otherwise.  If the TimeZone doesn't observe daylight savings
  360.      * time, this functions always returns false.
  361.      * @param date The date to test.
  362.      * @return true if the given date is in Daylight Savings Time;
  363.      * false otherwise.
  364.      */
  365.     virtual bool_t inDaylightTime(UDate date, UErrorCode& status) const;
  366.  
  367.     /**
  368.      * Return true if this zone has the same rules and offset as another zone.
  369.      * @param other the TimeZone object to be compared with
  370.      * @return true if the given zone has the same rules and offset as this one
  371.      */
  372.     bool_t hasSameRules(const TimeZone& other) const;
  373.  
  374.     /**
  375.      * Clones TimeZone objects polymorphically. Clients are responsible for deleting
  376.      * the TimeZone object cloned.
  377.      *
  378.      * @return   A new copy of this TimeZone object.
  379.      */
  380.     virtual TimeZone* clone(void) const;
  381.  
  382. public:
  383.  
  384.     /**
  385.      * Override TimeZone Returns a unique class ID POLYMORPHICALLY. Pure virtual
  386.      * override. This method is to implement a simple version of RTTI, since not all C++
  387.      * compilers support genuine RTTI. Polymorphic operator==() and clone() methods call
  388.      * this method.
  389.      *
  390.      * @return   The class ID for this object. All objects of a given class have the
  391.      *           same class ID. Objects of other classes have different class IDs.
  392.      */
  393.     virtual UClassID getDynamicClassID(void) const { return (UClassID)&fgClassID; }
  394.  
  395.     /**
  396.      * Return the class ID for this class. This is useful only for comparing to a return
  397.      * value from getDynamicClassID(). For example:
  398.      * <pre>
  399.      * .   Base* polymorphic_pointer = createPolymorphicObject();
  400.      * .   if (polymorphic_pointer->getDynamicClassID() ==
  401.      * .       Derived::getStaticClassID()) ...
  402.      * </pre>
  403.      * @return   The class ID for all objects of this class.
  404.      */
  405.     static UClassID getStaticClassID(void) { return (UClassID)&fgClassID; }
  406.  
  407. private:
  408.     /** 
  409.      * Constants specifying values of startMode and endMode.
  410.      */
  411.     enum EMode
  412.     {
  413.         DOM_MODE = 1,
  414.         DOW_IN_MONTH_MODE,
  415.         DOW_GE_DOM_MODE,
  416.         DOW_LE_DOM_MODE
  417.     };
  418.  
  419.     /**
  420.      * Compare a given date in the year to a rule. Return 1, 0, or -1, depending
  421.      * on whether the date is after, equal to, or before the rule date. The
  422.      * millis are compared directly against the ruleMillis, so any
  423.      * standard-daylight adjustments must be handled by the caller.
  424.      *
  425.      * @return  1 if the date is after the rule date, -1 if the date is before
  426.      *          the rule date, or 0 if the date is equal to the rule date.
  427.      */
  428.     static int32_t compareToRule(int32_t month, int32_t monthLen, int32_t dayOfMonth,
  429.                                      int32_t dayOfWeek, int32_t millis,
  430.                                      EMode ruleMode, int32_t ruleMonth, int32_t ruleDayOfWeek,
  431.                                      int32_t ruleDay, int32_t ruleMillis);
  432.  
  433.     /**
  434.      * Given a set of encoded rules in startDay and startDayOfMonth, decode
  435.      * them and set the startMode appropriately.  Do the same for endDay and
  436.      * endDayOfMonth.  
  437.      * <P>
  438.      * Upon entry, the day of week variables may be zero or
  439.      * negative, in order to indicate special modes.  The day of month
  440.      * variables may also be negative.
  441.      * <P>
  442.      * Upon exit, the mode variables will be
  443.      * set, and the day of week and day of month variables will be positive.
  444.      * <P>
  445.      * This method also recognizes a startDay or endDay of zero as indicating
  446.      * no DST.
  447.      */
  448.     void decodeRules(UErrorCode& status);
  449.     void decodeStartRule(UErrorCode& status);
  450.     void decodeEndRule(UErrorCode& status);
  451.  
  452.     static char     fgClassID;
  453.  
  454.     int32_t startMonth, startDay, startDayOfWeek;   // the month, day, DOW, and time DST starts
  455.     int32_t startTime;
  456.     int32_t endMonth, endDay, endDayOfWeek; // the month, day, DOW, and time DST ends
  457.     int32_t endTime;
  458.     int32_t startYear;  // the year these DST rules took effect
  459.     int32_t rawOffset;  // the TimeZone's raw GMT offset
  460.     bool_t useDaylight; // flag indicating whether this TimeZone uses DST
  461.     static const int32_t staticMonthLength[12]; // lengths of the months
  462.     EMode startMode, endMode;   // flags indicating what kind of rules the DST rules are
  463.  
  464.     /**
  465.      * A positive value indicating the amount of time saved during DST in ms.
  466.      * Typically one hour; sometimes 30 minutes.
  467.      */
  468.     int32_t dstSavings;
  469. };
  470.  
  471. #endif // _SIMPLETZ
  472.